OLA 文档中心

主题

2026-07-15

解析匹配图像JSON - ParseMatchImageJson ​

函数简介 ​

解析匹配图像 JSON 字符串，提取单个匹配结果的详细信息（坐标、宽高、相似度、角度等）。

接口名称 ​

ParseMatchImageJson

DLL调用 ​

c
int ParseMatchImageJson(string str, int* matchState, int* x, int* y, int* width, int* height, double* matchVal, double* angle, int* index);

参数说明 ​

参数名类型说明
str字符串匹配图像 JSON 字符串（单个对象，非数组）。
matchState整数型指针输出：匹配状态（非 0 表示匹配成功）。
x整数型指针输出：匹配点 X 坐标。
y整数型指针输出：匹配点 Y 坐标。
width整数型指针输出：匹配图片宽度。
height整数型指针输出：匹配图片高度。
matchVal双精度浮点数指针输出：匹配值。
angle双精度浮点数指针输出：匹配角度。
index整数型指针输出：匹配索引。

适用场景与联动 ​

本接口解析单结果 JSON（一个对象）。常见来源：

来源接口说明
MatchImageFromPath路径匹配，默认最优结果
MatchImageFromPtr内存图匹配
MatchImagePtrFromPath指针模板匹配
同类单结果接口如 MatchWindows*、FindImage*（非 All）、MatchAnimation* 等

原生 DLL 典型流程：

MatchImageFromPath / MatchImageFromPtr / ...
        ↓ 返回 JSON 字符串指针（非 0）
GetStringFromPtr 取出 JSON 文本
        ↓
ParseMatchImageJson 解析出 X/Y/MatchVal 等
        ↓
FreeStringPtr 释放指针

多结果 JSON 数组请使用 GetMatchImageAllCount + ParseMatchImageAllJson，不要用本接口。

示例 ​

SDK 调用 ​

cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
// 典型场景：已有单结果 JSON（与 MatchImageFromPath 原生返回格式一致）
// 例如从易语言 rawstring、文件、或原生 GetStringFromPtr 得到：
const char* resultJson =
    "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";

int32_t matchState = 0, x = 0, y = 0, width = 0, height = 0, index = 0;
double matchVal = 0, angle = 0;
int32_t ret = ola.ParseMatchImageJson(
    resultJson, &matchState, &x, &y, &width, &height, &matchVal, &angle, &index);

if (ret == 1 && matchState != 0) {
    // 匹配成功：可据此点击坐标 (x, y)
}
csharp
using OLAPlug;

var ola = new OLAPlugServer();
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
string resultJson =
    "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";

int ret = ola.ParseMatchImageJson(
    resultJson,
    out int matchState, out int x, out int y, out int width, out int height,
    out double matchVal, out double angle, out int index);

if (ret == 1 && matchState != 0)
{
    // 匹配成功：可据此点击坐标 (x, y)
}
python
from OLAPlugServer import OLAPlugServer

ola = OLAPlugServer()
# 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
result_json = '{"MatchState":true,"X":120,"Y":80,"Width":32,"Height":32,"MatchVal":0.95,"Angle":0,"Index":0}'
ret, match_state, x, y, width, height, match_val, angle, index = ola.ParseMatchImageJson(result_json)
if ret == 1 and match_state != 0:
    pass  # 匹配成功：可据此点击坐标 (x, y)
java
import com.olaplug.OLAPlugServer;

OLAPlugServer ola = new OLAPlugServer();
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
String resultJson =
    "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";
int[] out = new int[5];
double[] outD = new double[2];
int ret = ola.ParseMatchImageJson(resultJson, out, outD);
// 按 Java SDK 约定从 out / outD 取出 matchState、x、y 等后再判断
go
import "github.com/ola/olaplug/olaplug"

ola, _ := olaplug.NewOLAPlugServer("OLAPlug_x64.dll")
defer ola.ReleaseObj()
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
resultJson := "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}"
matchState, x, y, width, height, index := 0, 0, 0, 0, 0, 0
matchVal, angle := 0.0, 0.0
ret := ola.ParseMatchImageJson(resultJson, &matchState, &x, &y, &width, &height, &matchVal, &angle, &index)
if ret == 1 && matchState != 0 {
    // 匹配成功：可据此点击坐标 (x, y)
}
rust
use olaplug::OLAPlugServer;

let ola = OLAPlugServer::new("OLAPlug_x64.dll").unwrap();
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
let result_json = "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";
let mut match_state = 0i32;
let mut x = 0i32;
let mut y = 0i32;
let mut width = 0i32;
let mut height = 0i32;
let mut index = 0i32;
let mut match_val = 0.0f64;
let mut angle = 0.0f64;
let ret = ola.parse_match_image_json(
    result_json,
    &mut match_state, &mut x, &mut y, &mut width, &mut height,
    &mut match_val, &mut angle, &mut index,
);
if ret == 1 && match_state != 0 {
    // 匹配成功：可据此点击坐标 (x, y)
}
cpp
var ola = com("OlaPlug.OlaSoft")
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
var resultJson = "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}"
var matchState = 0, x = 0, y = 0, width = 0, height = 0, index = 0
var matchVal = 0.0, angle = 0.0
var ret = ola.ParseMatchImageJson(resultJson, matchState, x, y, width, height, matchVal, angle, index)
if (ret == 1 && matchState != 0) {
    // 匹配成功：可据此点击坐标 (x, y)
}
vbscript
Set ola = CreateObject("OlaPlug.OlaSoft")
' 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
resultJson = "{\""MatchState\"":true,\""X\"":120,\""Y\"":80,\""Width\"":32,\""Height\"":32,\""MatchVal\"":0.95,\""Angle\"":0,\""Index\"":0}"
Dim matchState, x, y, width, height, matchVal, angle, index
ret = ola.ParseMatchImageJson(resultJson, matchState, x, y, width, height, matchVal, angle, index)
If ret = 1 And matchState <> 0 Then
    ' 匹配成功：可据此点击坐标 (x, y)
End If
text
.局部变量 ola, OLAPlug
.局部变量 result, MatchData
.局部变量 rawstring, 文本型
.局部变量 ret, 整数型
.局部变量 matchState, 整数型
.局部变量 x, 整数型
.局部变量 y, 整数型
.局部变量 width, 整数型
.局部变量 height, 整数型
.局部变量 matchVal, 双精度小数型
.局部变量 angle, 双精度小数型
.局部变量 index, 整数型

ola.创建 ()
' 与 MatchImageFromPath 联动：第 7 个参数 rawstring 可拿到原始 JSON
result ＝ ola.MatchImageFromPath (“images/scene.png”, “img/template.bmp”, 0.9, 1, 0, 1, rawstring)
' 也可直接用 result.MatchState / result.X；需要手动解 JSON 时再用本接口：
ret ＝ ola.ParseMatchImageJson (rawstring, matchState, x, y, width, height, matchVal, angle, index)
.如果真 (ret ＝ 1 并且 matchState ≠ 0)
    ' 匹配成功：可据此点击坐标 (x, y)
.如果真结束
aardio
import OLAPlugServer;
var ola = OLAPlugServer();
// 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
var resultJson = "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";
var matchState, x, y, width, height, matchVal, angle, index;
var ret = ola.ParseMatchImageJson(resultJson, matchState, x, y, width, height, matchVal, angle, index);
if(ret == 1 && matchState != 0){
    // 匹配成功：可据此点击坐标 (x, y)
}
text
变量 ola <类型 = OLAPlugServer>
ola = 新建 OLAPlugServer
' 单结果 JSON：与 MatchImageFromPath 原生返回格式一致
文本型 resultJson = "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}"
整数 matchState = 0
整数 x = 0
整数 y = 0
整数 width = 0
整数 height = 0
整数 index = 0
双精度小数 matchVal = 0
双精度小数 angle = 0
整数 ret = ola.ParseMatchImageJson(resultJson, matchState, x, y, width, height, matchVal, angle, index)
如果真 (ret == 1 且 matchState != 0)
    ' 匹配成功：可据此点击坐标 (x, y)
如果真结束
cpp
#include "OLAPlugServer.h"

OLAPlugServer ola;
const char* resultJson =
    "{\"MatchState\":true,\"X\":120,\"Y\":80,\"Width\":32,\"Height\":32,\"MatchVal\":0.95,\"Angle\":0,\"Index\":0}";
int32_t matchState = 0, x = 0, y = 0, width = 0, height = 0, index = 0;
double matchVal = 0, angle = 0;
int32_t ret = ola.ParseMatchImageJson(
    resultJson, &matchState, &x, &y, &width, &height, &matchVal, &angle, &index);
if (ret == 1 && matchState != 0) {
    // 匹配成功：可据此点击坐标 (x, y)
}

原生 DLL 调用（与 MatchImage 完整联动） ​

cpp
long instance = CreateCOLAPlugInterFace();

// 1. 调用单结果匹配接口，成功时返回 JSON 字符串指针
long ptr = MatchImageFromPath(
    instance, "images/scene.png", "img/template.bmp", 0.9, 1, 0, 1);
if (ptr == 0) {
    // 未匹配到或失败
    return;
}

// 2. 取出 JSON 文本
char json[4096] = {0};
GetStringFromPtr(ptr, json, sizeof(json));

// 3. 用 ParseMatchImageJson 解析字段
int matchState = 0, x = 0, y = 0, width = 0, height = 0, index = 0;
double matchVal = 0, angle = 0;
int ret = ParseMatchImageJson(
    instance, json, &matchState, &x, &y, &width, &height, &matchVal, &angle, &index);

// 4. 释放匹配返回的字符串指针
FreeStringPtr(instance, ptr);

if (ret == 1 && matchState != 0) {
    // 匹配成功：使用 x, y, matchVal 等
}
csharp
using System.Runtime.InteropServices;
using System.Text;

[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long CreateCOLAPlugInterFace();
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern long MatchImageFromPath(long ola, string source, string templ, double matchVal, int type, double angle, double scale);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int GetStringFromPtr(long ptr, StringBuilder lpString, int size);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int GetStringSize(long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int FreeStringPtr(long ptr);
[DllImport("OLAPlug_x64.dll", CallingConvention = CallingConvention.StdCall)]
static extern int ParseMatchImageJson(long ola, string str, out int matchState, out int x, out int y, out int width, out int height, out double matchVal, out double angle, out int index);

long instance = CreateCOLAPlugInterFace();

// 1. MatchImageFromPath → JSON 指针
long ptr = MatchImageFromPath(instance, "images/scene.png", "img/template.bmp", 0.9, 1, 0, 1);
if (ptr == 0) return;

// 2. 取出 JSON
var sb = new StringBuilder(GetStringSize(ptr) + 1);
GetStringFromPtr(ptr, sb, sb.Capacity);
string json = sb.ToString();
FreeStringPtr(ptr);

// 3. 解析
int ret = ParseMatchImageJson(
    instance, json,
    out int matchState, out int x, out int y, out int width, out int height,
    out double matchVal, out double angle, out int index);

if (ret == 1 && matchState != 0)
{
    // 匹配成功：使用 x, y, matchVal 等
}
python
from ctypes import CDLL, c_int, c_int64, c_double, create_string_buffer

ola = CDLL("OLAPlug_x64.dll")
ola.CreateCOLAPlugInterFace.restype = c_int64
ola.MatchImageFromPath.restype = c_int64
instance = ola.CreateCOLAPlugInterFace()

# 1. MatchImageFromPath → JSON 指针
ptr = ola.MatchImageFromPath(
    instance, b"images/scene.png", b"img/template.bmp",
    c_double(0.9), c_int(1), c_double(0), c_double(1))
if ptr == 0:
    raise RuntimeError("match failed")

# 2. 取出 JSON
size = ola.GetStringSize(ptr)
buf = create_string_buffer(size + 1)
ola.GetStringFromPtr(ptr, buf, size + 1)
ola.FreeStringPtr(instance, ptr)  # 按所用封装签名调整
result_json = buf.value

# 3. 解析
match_state = c_int(0)
x = c_int(0)
y = c_int(0)
width = c_int(0)
height = c_int(0)
index = c_int(0)
match_val = c_double(0)
angle = c_double(0)
ret = ola.ParseMatchImageJson(
    instance, result_json,
    match_state, x, y, width, height, match_val, angle, index)
if ret == 1 and match_state.value != 0:
    pass  # 匹配成功：使用 x.value, y.value 等

返回值 ​

错误码含义见 JSON 错误码说明。

返回值说明
1成功。
0失败（格式不符、空串等）。

注意事项 ​

项目说明
仅解析单结果对象JSON 须为单个对象；数组请用 ParseMatchImageAllJson。
与 SDK 结构化返回的关系C++/C#/Python 等 SDK 的 MatchImageFromPath 已直接返回 MatchData，一般无需再解析；本接口主要用于原生 DLL、易语言 rawstring、或其它拿到原始 JSON 的场景。
输出参数所有输出参数须提供有效指针/变量。
内存释放原生路径务必对匹配返回的指针调用 FreeStringPtr。